本章目标
- 熟悉前端开发工作流：从接口定义到 Mock 数据，再到页面渲染的完整流程
- 掌握接口文档定义能力：学会根据页面需求设计接口数据结构
注意：实际工作中接口文档应在需求分析阶段完成，先于页面开发。本课程为了教学效率，将接口定义放在页面开发之后。
全站接口分析
首页接口
首页将多个数据合并为一个接口返回，避免多次请求造成性能损耗：
GET /api/v1/home
text
响应数据包含四组内容：
| 字段 | 类型 | 说明 |
|---|---|---|
swipes | object[] | 头部轮播图数据 |
projects | object[] | 项目推荐列表 |
courses | object[] | 推荐课程列表 |
swipeProjects | object[] | 底部项目轮播展示 |
对象内部字段：
| 字段 | 类型 | 说明 |
|---|---|---|
image | string | 图片链接 |
title | string | 标题 |
subtitle | string | 副标题 |
url | string | 跳转链接 |
id | number | 唯一标识 |
icon | string | Iconify 图标 class |
项目详情接口
GET /api/v1/project/:id
text
返回项目详情信息，包含 Markdown 内容文件路径、合作方信息、团队宣言等。
学习页面接口
学习页面数据较多，需响应六类数据：
| 数据类型 | 说明 |
|---|---|
| 推荐内容 | 精选推荐课程列表 |
| 每日一课 | 每日推荐课程 |
| 精品微课 | 短课程推荐 |
| 学习计划 | 学习路径规划 |
| 优质专栏 | 专栏文章推荐 |
| 背景图片 | 页面背景图 |
其他接口一览
| 接口 | 方法 | 路径 | 说明 |
|---|---|---|---|
| 学习列表 | GET | /study | 学习页面数据 |
| 搜索课程 | GET | /search | 按名称搜索课程 |
| 登录 | POST | /login | 用户登录 |
| 注册 | POST | /register | 用户注册 |
| 课程详情 | GET | /course/:id | 课程详情信息 |
| 下单 | POST | /order | 创建订单 |
| 会员信息 | GET | /vip | VIP 会员信息 |
| 课程评价 | GET | /comments | 课程评价列表 |
接口文档编写规范
接口命名规范
建议采用 模块-请求方式-功能 的格式：
home-get-detail // 首页-GET-详情
study-get-list // 学习-GET-列表
order-post-create // 订单-POST-创建
text
关键原则：团队内保持统一的命名规范，避免不同开发者使用不同风格。
错误代码设计
错误代码使用 模块_子模块_错误原因 的命名格式：
格式一：常量导出
export const HOME_SWIPES_NOT_FOUND = 10000
export const SUCCESS = 200
ts
格式二：表格形式（推荐）
| 错误类型 | 错误代码 | 说明 |
|---|---|---|
SUCCESS | 200 | 正常响应 |
HOME_SWIPES_NOT_FOUND | 10000 | 请求轮播头图失败 |
HOME_PROJECTS_ERROR | 10001 | 请求项目列表失败 |
重要提示：错误代码是服务端响应给前端的自定义业务码，不是 HTTP 状态码。
接口文档工具
使用 ShowDoc 等接口文档管理工具，按模块创建接口页面：
- 每个接口定义请求路径、方法、参数和响应示例
- 响应数据结构使用 JSON 格式，所有字段值使用双引号
- 底部附上字段说明表格
参考规范
微信小程序的错误码设计可作为参考：错误码以负数开头，范围从 -400000 到 -600000，每个范围对应不同模块。
首页接口数据结构设计
{
"code": 200,
"data": {
"swipes": [
{
"image": "/api/image/bg.png",
"url": "/project/1"
}
],
"projects": [
{
"icon": "i-mdi-vuejs",
"title": "Vue3 实战",
"id": 1
}
],
"courses": [
{
"image": "/api/image/course1.png",
"title": "前端大前端",
"subtitle": "从入门到精通",
"url": "/course/1"
}
],
"swipeProjects": [
{
"image": "/api/image/proj1.png",
"url": "/project/2"
}
]
}
}
json
购物车流程说明
购物车采用简化设计：
- 添加购物车：仅本地缓存，不请求服务端
- 点击结算：弹出付款码，此时与用户 ID 绑定
- 付款状态查询：通过轮询（Polling）或 WebSocket 查询服务端是否确认收款
课程详情接口设计要点
课程详情页需要多个数据源，但不必在一个接口中全部返回：
1. 首次加载：获取课程基本信息（名称、描述、作者、价格）
2. 立即加载：章节目录数据
3. 延迟加载：学员评价（滚动到对应区域后再请求）
text
这种分步加载策略可以减少首屏请求体积，提升用户体验。
↑